home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Source Code / Add-Ons / After Dark / The Swarm 1.0 / The Swarm README < prev    next >
Encoding:
Text File  |  1994-03-28  |  9.8 KB  |  220 lines  |  [TEXT/R*ch]
  1. ---------------------------------------------------------------------------
  2. THE SWARM v1.0  -  A freeware After Dark module
  3.  
  4. By Leo Breebaart, Kronto Software 1994
  5. Internet e-mail: leo@cp.tn.tudelft.nl            “Bee, where is thy Sting?”
  6. ---------------------------------------------------------------------------
  7.  
  8.  
  9. Description
  10. -----------
  11.  
  12.   The Swarm is a very simple, but surprisingly elegant and mesmerizing
  13.   line animation, in which a number of small line segments (the ‘bees’)
  14.   chase one other segment (the ‘queen bee’) across the screen.
  15.   
  16.  
  17. Features
  18. --------
  19.  
  20.   •  Fast, flicker-free animation.
  21.   •     Does not use any permanent System memory.
  22.   •  Smooth fade-out/fade-in effects.
  23.   •  Animated About Box.
  24.   •  Intelligent Demo Mode (as if anybody cares :-)).
  25.   •  Runs under both MultiModule and the Randomizer -- without crashing.
  26.   •  Compatible with both Tom Dowdy’s “DarkSide of the Mac” screensaver
  27.        and Steve Falkenburg’s “Twilight Zone” stand-alone module player.
  28.   •  Comes with extensively documented source code (THINK C 6.0.1 format).
  29.   •  Both the module and the source code are freeware.
  30.   
  31.  
  32. Restrictions
  33. ------------
  34.  
  35.   •     Needs Color QuickDraw. A color *screen* is not essential, however: 
  36.      on a Black & White SE/30 the module works just fine.
  37.   •  No support yet for multiple-monitor setups -- the animation always
  38.      runs on the main monitor only (and will simply black out any other screens).
  39.   •  No guarantees for versions of After Dark prior to 2.0u, nor for any 
  40.      other programs that are supposed to be able to play After Dark modules.
  41.      In all such cases, The Swarm may run, or it may not. Feedback about 
  42.      compatibility will be much appreciated. More information about version
  43.      numbers and upgrades can be found further down in this file.
  44.         
  45.  
  46. Who thought of it first
  47. -----------------------
  48.  
  49.   I first came across this animation in an X Windows program called ‘xswarm’,
  50.   written by Jeff Butterworth in the early 90’s. I liked it so much, that I
  51.   decided to write an After Dark version. Most of the module I had to create
  52.   from scratch, but the core algorithm was taken straight from Jeff’s
  53.   sources. My module, of course, lacks all the many options that his X Windows
  54.   program has. If you have access to an appropriate machine, be sure to
  55.   check out ‘xswarm’ -- it’s great.
  56.   
  57.   My thanks to Jeff for giving me permission to ransack his code and port his
  58.   algorithm to the Mac.
  59.   
  60.   
  61. Who else thought of it first
  62. ----------------------------
  63.  
  64.   Shortly after I began programming this module it was brought to my
  65.   attention that there already *was* a ‘swarm’ After Dark module, called
  66.   “ColorSwarm!”, written by Dan Walkowski in 1991.
  67.  
  68.   Since his module looked a bit different from what I had in mind, I just went
  69.   ahead and wrote my own version anyway. But be sure to check out his work. 
  70.   He has more parameters for you to set, his “ColorSwarm!” works on B&W machines 
  71.   without Color QuickDraw, and I believe he also handles multiple monitors, 
  72.   which I don’t.
  73.   
  74.   
  75. Other credits
  76. -------------
  77.  
  78.   For technical assistance, emotional support and beta-testing I owe a sincere 
  79.   thank-you to Rodney “Jewelbox” Jacks, to Lloyd “Screensaver FAQ” Wood, and to 
  80.   all the members of the After Dark programmer’s mailing list.
  81.  
  82.   Special thanks to Jonas Englund, for allowing me to use and distribute
  83.   his CLUT fading code.
  84.   
  85.   Extra special thanks to David “Bat Signal” Zwiefelhofer, to Joseph 
  86.   “Peek-a-Boo” Judge, and to Berkeley Systems themselves for releasing sample 
  87.   source code and documentation without which this module would never have 
  88.   been written in the first place.
  89.   
  90.   
  91. Known Problems
  92. --------------
  93.  
  94.   •     The ‘smooth fade’ option only works on 8-bit CLUT screens, but the check 
  95.      box may appear on monitors that do not qualify as such. This is 
  96.      completely harmless — the check box will simply have no effect on the
  97.      module, and no fading will take place.
  98.   •  On grayscale monitors the animation will be in black and white. This is
  99.      not a problem, but a conscious decision: trying to use shades of gray
  100.      simply does not Look Good.
  101.   •     Under “DarkSide of the Mac” I have sometimes noticed that certain
  102.        parameters do not have the right initial values. The mini-animation
  103.        in the About Box is sometimes delayed when it shouldn’t be, and the
  104.        swarm will appear ‘colored’ on grayscale displays. Weird, huh?
  105.   •     Those of you interested in the source code should be aware that I am
  106.        not an experienced Macintosh programmer -- in fact, The Swarm is my
  107.        very first programming effort for the Mac. This means that the code
  108.        may have hidden problems that I’m simply not aware of. Don’t assume
  109.        that I’m always doing things the ‘right’ way!
  110.        
  111.   I would appreciate hearing about any other bugs or problems you may encounter 
  112.   with The Swarm, but please try make sure that you are running the latest 
  113.   versions of After Dark or DarkSide of the Mac. At the moment of writing the 
  114.   current version numbers are 2.0x for After Dark (2.0y if you have the Disney 
  115.   Collection) and 4.1 for DarkSide. Free updaters for these programs are readily 
  116.   available on the Internet and on all the major commercial software archives.
  117.         
  118.         
  119. A Word about Memory and CPU-time
  120. --------------------------------
  121.  
  122.   The Swarm tries to be a well-behaved, system-friendly module. It will, for
  123.   instance, *not* reserve any permanent memory in your system heap. That
  124.   means that having The Swarm selected costs you no more memory than having
  125.   the default ‘Starry Night’ module selected, *as long as After Dark has not
  126.   taken over the screen*.
  127.   
  128.   Of course, once After Dark kicks in, The Swarm *does* need loads of memory
  129.   for its animation (the larger your screen the worse it gets :-)), which it
  130.   will try to allocate out of the free memory you have at that moment. In
  131.   low-memory situations (e.g. if you have lots of applications open), this
  132.   attempt may be unsuccessful, and the module will refuse to run with an
  133.   appropriate error message. The reason I am explaining all of this in such
  134.   detail is that the upshot of this strategy is that you may see The Swarm
  135.   ‘fail’ to run more often than other modules. But that is entirely
  136.   intentional, and only means that it is your real applications which are
  137.   getting access to every last Kb of your available memory. Isn’t that how 
  138.   things should be?
  139.   
  140.   On fast Macs (Quadra’s or higher), finally, you will want to use the ‘Swarm
  141.   Speed’ slider in the control panel to slow the animation down. Here too, I 
  142.   just want to point out that if you do this, then the extra CPU time will be
  143.   given back to the system. The Swarm will never use more processing power
  144.   then it really needs.
  145.  
  146.         
  147. Still To Do
  148. -----------
  149.  
  150.   There will be a next version of The Swarm, although for the coming months
  151.   (I’m writing this in March 1994) I will not have time to work on it.
  152.   For The Swarm v2.0 I intend the following features and fixes:
  153.   
  154.   •  Support multiple monitors.
  155.   •  Support old, non-Color Quickdraw B&W Macs.
  156.   •  Fix the Known Problems.
  157.   •  Make Bees change color over time.
  158.   •     Make Queen Bee behave more intelligently and interestingly.
  159.   •  Multiple Swarms, or multiple Queen Bees (there’s a difference!).
  160.   •  Add sound/music.
  161.   •  Add more parameters for you to play with.
  162.   •  Make a specific “DarkSide of the Mac” version.
  163.   •  Add an option to make the entire Swarm move 3-dimensionally, with
  164.      depth indicated by perspective projection and color brightness.
  165.  
  166.   If you have any suggestions to add to this list, let me know.
  167.   
  168.   
  169. A request
  170. ---------
  171.  
  172.   As mentioned before, this module and its source code are released as 
  173.   freeware. Do with them whatever you like, and feel free to use as much of 
  174.   my code as you like in your own programs. Just one small request: please 
  175.   do not hack the source code, recompile it, and then release your own version
  176.   of The Swarm. Instead, if you have made modifications, let me know about it, 
  177.   and I’ll see if I can incorporate it into the next version.
  178.   
  179.   Whether you are a programmer or not: feel free to send any kind of feedback 
  180.   my way. Bug reports, wish lists, comments, questions -- everything is more 
  181.   than welcome.
  182.     
  183.   
  184. Miscellaneous Stuff
  185. -------------------
  186.  
  187.   Internet-connected people can find the original xswarm program on the 
  188.   X Windows ftp site: ftp.x.org:/contrib.
  189.  
  190.   The most recent version of the After Dark programmer’s interface (which also
  191.   gets updated sometimes -- the copy that came with your diskette may be outdated)
  192.   is available from the major Internet archive sites such as sumex.stanford.edu, 
  193.   mac.archive.umich.edu and their mirrors. So are the DarkSide of the Mac and 
  194.   Twilight Zone packages, as well as the After Dark 2.0x updater. 
  195.   
  196.   If you want to write After Dark modules yourself, consider joining the
  197.   After Dark programmer’s mailing list. In order to subscribe, send mail
  198.   to afterdark-request@clipper.att.com.
  199.   
  200.   Associated with the mailing list is the After Dark ftp site, where you will
  201.   find lots of After Dark-related material, including many modules as well as 
  202.   special programmer’s information. For those of you connected to the Internet: 
  203.   a convenient way to access the After Dark ftp site is by using the bookmark 
  204.   file included in this distribution of The Swarm. This bookmark can be opened 
  205.   (just double-click it) by Fetch (v2.1.2 or later) or Anarchie (v1.0.3 or later),
  206.   two ftp-aware applications that no Mac on the Internet should be without. You 
  207.   will then directly be transported to what in more conventional terms would be 
  208.   described as ftp.att.com:/pub/afterdark.
  209.    
  210.   Finally, nobody who owns a Macintosh screensaver package should be without 
  211.   the most recent version of Lloyd Wood’s Screensaver FAQ (Frequently Asked 
  212.   Questions List). Copies of this list are also available from all major 
  213.   archive sites on or off the Internet. It is a must-have. Trust me.
  214.   
  215.   
  216. Enjoy,
  217.  
  218. --
  219. Leo Breebaart (leo@cp.tn.tudelft.nl)
  220.